<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Block Level Elements</title>
<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../../quickbook.html" title="Chapter 46. Quickbook 1.7">
<link rel="prev" href="phrase.html" title="Phrase Level Elements">
<link rel="next" href="../versions.html" title="Language Versions">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
<td align="center"><a href="../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="phrase.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../quickbook.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../versions.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="quickbook.syntax.block"></a>Block Level Elements</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="block.html#quickbook.syntax.block.xinclude">xinclude</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.paragraphs">Paragraphs</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists">Lists</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.code">Code</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.escape_back">Escaping
      Back To QuickBook</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.preformatted">Preformatted</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.blockquote">Blockquote</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.admonitions">Admonitions</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.headings">Headings</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.generic_heading">Generic
      Heading</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.macros">Macros</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.predefined_macros">Predefined
      Macros</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.templates">Templates</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.blurbs">Blurbs</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.tables">Tables</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.variable_lists">Variable
      Lists</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.include">Include</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.import">Import</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.block">Plain
      blocks</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.xinclude"></a><a name="quickbook.ref.xinclude"></a><a class="link" href="block.html#quickbook.syntax.block.xinclude" title="xinclude">xinclude</a>
</h3></div></div></div>
<p>
        You can include another XML file with:
      </p>
<pre class="programlisting">[xinclude file.xml]
</pre>
<p>
        This is useful when file.xml has been generated by Doxygen and contains your
        reference section.
      </p>
<p>
        <code class="literal">xinclude</code> paths are normally used unchanged in the generated
        documentation, which will not work if you wish them to be relative to the
        current quickbook file. Quickbook can add a <code class="literal">xml:base</code> attribute
        to the boostbook documentation to specify where <code class="literal">xinclude</code>
        files should be found. For example, if you wish them to be relative to the
        current quickbook file:
      </p>
<pre class="programlisting">[article Article with xincludes
[quickbook 1.7]
[xmlbase .]
]

[xinclude file.xml]
</pre>
<p>
        Now the xinclude should work if <code class="literal">file.xml</code> is in the same
        directory as the quickbook file. Although it might not work if you distribute
        the generated files (as their relative directories can change).
      </p>
<p>
        Say the article is generated in a sub-directory, by running something like:
      </p>
<pre class="programlisting">quickbook article.qbk --output-file=output/article.xml
</pre>
<p>
        This will generate a boostbook root tag:
      </p>
<pre class="programlisting">&lt;article id="article_with_xincludes"
    last-revision="$Date: 2013/08/20 08:26:48 $"
    xml:base=".."
    xmlns:xi="http://www.w3.org/2001/XInclude"&gt;
</pre>
<p>
        Because <code class="literal">xml:base</code> is set to <code class="literal">..</code>, the
        xml processor will know to look in the parent directory to find <code class="literal">file.xml</code>,
        which it comes across the <code class="literal">xi:include</code> tag.
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.paragraphs"></a><a name="quickbook.ref.paragraphs"></a><a class="link" href="block.html#quickbook.syntax.block.paragraphs" title="Paragraphs">Paragraphs</a>
</h3></div></div></div>
<p>
        Paragraphs start left-flushed and are terminated by two or more newlines.
        No markup is needed for paragraphs. QuickBook automatically detects paragraphs
        from the context. Block markups [section, endsect, h1, h2, h3, h4, h5, h6,
        blurb, (block-quote) ':', pre, def, table and include ] may also terminate
        a paragraph. This is a new paragraph...
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.lists"></a><a name="quickbook.ref.lists"></a><a class="link" href="block.html#quickbook.syntax.block.lists" title="Lists">Lists</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.ordered_lists">Ordered
        lists</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.list_hierarchies">List
        Hierarchies</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.long_list_lines">Long
        List Lines</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.unordered_lists">Unordered
        lists</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.mixed_lists">Mixed
        lists</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.list_paragraphs">Paragraphs
        in lists</a></span></dt>
<dt><span class="section"><a href="block.html#quickbook.syntax.block.lists.list_tags">Explicit
        list tags</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.syntax.block.lists.ordered_lists"></a><a name="quickbook.ref.ordered_lists"></a><a class="link" href="block.html#quickbook.syntax.block.lists.ordered_lists" title="Ordered lists">Ordered
        lists</a>
</h4></div></div></div>
<pre class="programlisting"># One
# Two
# Three
</pre>
<p>
          will generate:
        </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
              One
            </li>
<li class="listitem">
              Two
            </li>
<li class="listitem">
              Three
            </li>
</ol></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.syntax.block.lists.list_hierarchies"></a><a name="quickbook.ref.list_hierarchies"></a><a class="link" href="block.html#quickbook.syntax.block.lists.list_hierarchies" title="List Hierarchies">List
        Hierarchies</a>
</h4></div></div></div>
<p>
          List hierarchies are supported. Example:
        </p>
<pre class="programlisting"># One
# Two
# Three
    # Three.a
    # Three.b
    # Three.c
# Four
    # Four.a
        # Four.a.i
        # Four.a.ii
# Five
</pre>
<p>
          will generate:
        </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
              One
            </li>
<li class="listitem">
              Two
            </li>
<li class="listitem">
              Three
              <div class="orderedlist"><ol class="orderedlist" type="a">
<li class="listitem">
                    Three.a
                  </li>
<li class="listitem">
                    Three.b
                  </li>
<li class="listitem">
                    Three.c
                  </li>
</ol></div>
            </li>
<li class="listitem">
              Fourth
              <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem">
                    Four.a
                    <div class="orderedlist"><ol class="orderedlist" type="i">
<li class="listitem">
                          Four.a.i
                        </li>
<li class="listitem">
                          Four.a.ii
                        </li>
</ol></div>
                  </li></ol></div>
            </li>
<li class="listitem">
              Five
            </li>
</ol></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.syntax.block.lists.long_list_lines"></a><a name="quickbook.ref.long_list_lines"></a><a class="link" href="block.html#quickbook.syntax.block.lists.long_list_lines" title="Long List Lines">Long
        List Lines</a>
</h4></div></div></div>
<p>
          Long lines will be wrapped appropriately. Example:
        </p>
<pre class="programlisting"># A short item.
# A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
  A very long item. A very long item. A very long item.
# A short item.
</pre>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
              A short item.
            </li>
<li class="listitem">
              A very long item. A very long item. A very long item. A very long item.
              A very long item. A very long item. A very long item. A very long item.
              A very long item. A very long item. A very long item. A very long item.
              A very long item. A very long item. A very long item.
            </li>
<li class="listitem">
              A short item.
            </li>
</ol></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.syntax.block.lists.unordered_lists"></a><a name="quickbook.ref.unordered_lists"></a><a class="link" href="block.html#quickbook.syntax.block.lists.unordered_lists" title="Unordered lists">Unordered
        lists</a>
</h4></div></div></div>
<pre class="programlisting">* First
* Second
* Third
</pre>
<p>
          will generate:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              First
            </li>
<li class="listitem">
              Second
            </li>
<li class="listitem">
              Third
            </li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.syntax.block.lists.mixed_lists"></a><a name="quickbook.ref.mixed_lists"></a><a class="link" href="block.html#quickbook.syntax.block.lists.mixed_lists" title="Mixed lists">Mixed
        lists</a>
</h4></div></div></div>
<p>
          Mixed lists (ordered and unordered) are supported. Example:
        </p>
<pre class="programlisting"># One
# Two
# Three
    * Three.a
    * Three.b
    * Three.c
# Four
</pre>
<p>
          will generate:
        </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
              One
            </li>
<li class="listitem">
              Two
            </li>
<li class="listitem">
              Three
              <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
                    Three.a
                  </li>
<li class="listitem">
                    Three.b
                  </li>
<li class="listitem">
                    Three.c
                  </li>
</ul></div>
            </li>
<li class="listitem">
              Four
            </li>
</ol></div>
<p>
          And...
        </p>
<pre class="programlisting"># 1
    * 1.a
        # 1.a.1
        # 1.a.2
    * 1.b
# 2
    * 2.a
    * 2.b
        # 2.b.1
        # 2.b.2
            * 2.b.2.a
            * 2.b.2.b
</pre>
<p>
          will generate:
        </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
              1
              <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
                    1.a
                    <div class="orderedlist"><ol class="orderedlist" type="a">
<li class="listitem">
                          1.a.1
                        </li>
<li class="listitem">
                          1.a.2
                        </li>
</ol></div>
                  </li>
<li class="listitem">
                    1.b
                  </li>
</ul></div>
            </li>
<li class="listitem">
              2
              <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
                    2.a
                  </li>
<li class="listitem">
                    2.b
                    <div class="orderedlist"><ol class="orderedlist" type="a">
<li class="listitem">
                          2.b.1
                        </li>
<li class="listitem">
                          2.b.2
                          <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
<li class="listitem">
                                2.b.2.a
                              </li>
<li class="listitem">
                                2.b.2.b
                              </li>
</ul></div>
                        </li>
</ol></div>
                  </li>
</ul></div>
            </li>
</ol></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.syntax.block.lists.list_paragraphs"></a><a name="quickbook.ref.list_paragraphs"></a><a class="link" href="block.html#quickbook.syntax.block.lists.list_paragraphs" title="Paragraphs in lists">Paragraphs
        in lists</a>
</h4></div></div></div>
<p>
          In quickbook 1.7 onwards, you can nest paragraphs in lists by separating
          them with blank lines:
        </p>
<pre class="programlisting">* List item 1, paragraph 1

  List item 1, paragraph 2

* List item 2, paragraph 1

  List item 2, paragraph 2
</pre>
<p>
          will generate:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p class="simpara">
              List item 1, paragraph 1
            </p>
<p class="simpara">
              List item 1, paragraph 2
            </p>
</li>
<li class="listitem">
<p class="simpara">
              List item 2, paragraph 1
            </p>
<p class="simpara">
              List item 2, paragraph 2
            </p>
</li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="quickbook.syntax.block.lists.list_tags"></a><a name="quickbook.ref.list_tags"></a><a class="link" href="block.html#quickbook.syntax.block.lists.list_tags" title="Explicit list tags">Explicit
        list tags</a>
</h4></div></div></div>
<p>
          Sometimes the wiki-style list markup can be tricky to use, especially if
          you wish to include more complicated markup with the list. So in quickbook
          1.6, an alternative way to mark up lists introduced:
        </p>
<pre class="programlisting">[ordered_list [item1][item2]]
</pre>
<p>
          is equivalent to:
        </p>
<pre class="programlisting"># item1
# item2
</pre>
<p>
          And:
        </p>
<pre class="programlisting">[itemized_list [item1][item2]]
</pre>
<p>
          is equivalent to:
        </p>
<pre class="programlisting">* item1
* item2
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.code"></a><a name="quickbook.ref.code"></a><a class="link" href="block.html#quickbook.syntax.block.code" title="Code">Code</a>
</h3></div></div></div>
<p>
        Preformatted code starts with a space or a tab. The code will be syntax highlighted
        according to the current <a class="link" href="phrase.html#quickbook.ref.source_mode">Source
        Mode</a>:
      </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
<span class="special">{</span>
    <span class="comment">// Sample code</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello, World\n"</span><span class="special">;</span>
    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<pre class="programlisting"><span class="keyword">import</span> <span class="identifier">cgi</span>

<span class="keyword">def</span> <span class="identifier">cookForHtml</span><span class="special">(</span><span class="identifier">text</span><span class="special">):</span>
    <span class="string">'''"Cooks" the input text for HTML.'''</span>

    <span class="keyword">return</span> <span class="identifier">cgi</span><span class="special">.</span><span class="identifier">escape</span><span class="special">(</span><span class="identifier">text</span><span class="special">)</span>
</pre>
<p>
        Macros that are already defined are expanded in source code. Example:
      </p>
<pre class="programlisting">[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]

    using __boost__::__array__;
</pre>
<p>
        Generates:
      </p>
<pre class="programlisting">using <a href="http://www.boost.org/libs/libraries.htm" target="_top">boost</a>::<a href="http://www.boost.org/doc/html/array/reference.html" target="_top">array</a>;
</pre>
<p>
        In quickbook 1.7 and later, you can include <a class="link" href="block.html#quickbook.ref.callouts">callouts</a>
        in code blocks, like so:
      </p>
<pre class="programlisting">[!c++]
    std::string foo_bar() /*&lt; The /Mythical/ FooBar.
                          See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] &gt;*/
    {
        return "foo-bar"; /*&lt; return 'em, foo-bar man! &gt;*/
    }
</pre>
<p>
        Which will generate:
      </p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo_bar</span><span class="special">()</span> <a class="co" name="quickbook.syntax.block.code.c0" href="block.html#quickbook.syntax.block.code.c1"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
<span class="special">{</span>
    <span class="keyword">return</span> <span class="string">"foo-bar"</span><span class="special">;</span> <a class="co" name="quickbook.syntax.block.code.c2" href="block.html#quickbook.syntax.block.code.c3"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a>
<span class="special">}</span>
</pre>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.code.c1"></a><a href="#quickbook.syntax.block.code.c0"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
            The <span class="emphasis"><em>Mythical</em></span> FooBar. See <a href="http://en.wikipedia.org/wiki/Foobar" target="_top">Foobar
            for details</a>
          </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.code.c3"></a><a href="#quickbook.syntax.block.code.c2"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
<td valign="top" align="left"><p>
            return 'em, foo-bar man!
          </p></td>
</tr>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.escape_back"></a><a name="quickbook.ref.escape_back"></a><a class="link" href="block.html#quickbook.syntax.block.escape_back" title="Escaping Back To QuickBook">Escaping
      Back To QuickBook</a>
</h3></div></div></div>
<p>
        Inside code, code blocks and inline code, QuickBook does not allow any markup
        to avoid conflicts with the target syntax (e.g. c++). In case you need to
        switch back to QuickBook markup inside code, you can do so using a language
        specific <span class="emphasis"><em>escape-back</em></span> delimiter. In C++ and Python, the
        delimiter is the double tick (back-quote): "``" and "``".
        Example:
      </p>
<pre class="programlisting">void <a href="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz" target="_top">foo</a>()
{
}
</pre>
<p>
        Will generate:
      </p>
<pre class="programlisting">void <a href="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz" target="_top">foo</a>()
{
}
</pre>
<p>
        When escaping from code to QuickBook, only phrase level markups are allowed.
        Block level markups like lists, tables etc. are not allowed.
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.preformatted"></a><a name="quickbook.ref.preformatted"></a><a class="link" href="block.html#quickbook.syntax.block.preformatted" title="Preformatted">Preformatted</a>
</h3></div></div></div>
<p>
        Sometimes, you don't want some preformatted text to be parsed as source code.
        In such cases, use the <code class="literal">[pre ... ]</code> markup block.
      </p>
<pre class="programlisting">[pre

    Some *preformatted* text                    Some *preformatted* text

        Some *preformatted* text            Some *preformatted* text

            Some *preformatted* text    Some *preformatted* text

]
</pre>
<p>
        Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block
        level markup, pre (and Code) are the only ones that allow multiple newlines.
        The markup above will generate:
      </p>
<pre class="programlisting">
Some <span class="bold"><strong>preformatted</strong></span> text                    Some <span class="bold"><strong>preformatted</strong></span> text

    Some <span class="bold"><strong>preformatted</strong></span> text            Some <span class="bold"><strong>preformatted</strong></span> text

        Some <span class="bold"><strong>preformatted</strong></span> text    Some <span class="bold"><strong>preformatted</strong></span> text

</pre>
<p>
        Notice that unlike Code, phrase markup such as font style is still permitted
        inside <code class="literal">pre</code> blocks.
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.blockquote"></a><a name="quickbook.ref.blockquote"></a><a class="link" href="block.html#quickbook.syntax.block.blockquote" title="Blockquote">Blockquote</a>
</h3></div></div></div>
<pre class="programlisting">[:sometext...]
</pre>
<div class="blockquote"><blockquote class="blockquote"><p>
          Indents the paragraph. This applies to one paragraph only.
        </p></blockquote></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.admonitions"></a><a name="quickbook.ref.admonitions"></a><a class="link" href="block.html#quickbook.syntax.block.admonitions" title="Admonitions">Admonitions</a>
</h3></div></div></div>
<pre class="programlisting">[note This is a note]
[tip This is a tip]
[important This is important]
[caution This is a caution]
[warning This is a warning]
</pre>
<p>
        generates <a href="http://www.docbook.org/" target="_top">DocBook</a> admonitions:
      </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
          This is a note
        </p></td></tr>
</table></div>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
          This is a tip
        </p></td></tr>
</table></div>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
          This is important
        </p></td></tr>
</table></div>
<div class="caution"><table border="0" summary="Caution">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
<th align="left">Caution</th>
</tr>
<tr><td align="left" valign="top"><p>
          This is a caution
        </p></td></tr>
</table></div>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
          This is a warning
        </p></td></tr>
</table></div>
<p>
        These are the only admonitions supported by <a href="http://www.docbook.org/" target="_top">DocBook</a>.
        So, for example <code class="literal">[information This is some information]</code>
        is unlikely to produce the desired effect.
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.headings"></a><a name="quickbook.ref.headings"></a><a class="link" href="block.html#quickbook.syntax.block.headings" title="Headings">Headings</a>
</h3></div></div></div>
<pre class="programlisting">[h1 Heading 1]
[h2 Heading 2]
[h3 Heading 3]
[h4 Heading 4]
[h5 Heading 5]
[h6 Heading 6]
</pre>
<h2>
<a name="quickbook.syntax.block.headings.h0"></a>
        <span class="phrase"><a name="quickbook.syntax.block.headings.heading_1"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_1">Heading
        1</a>
      </h2>
<h3>
<a name="quickbook.syntax.block.headings.h1"></a>
        <span class="phrase"><a name="quickbook.syntax.block.headings.heading_2"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_2">Heading
        2</a>
      </h3>
<h4>
<a name="quickbook.syntax.block.headings.h2"></a>
        <span class="phrase"><a name="quickbook.syntax.block.headings.heading_3"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_3">Heading
        3</a>
      </h4>
<h5>
<a name="quickbook.syntax.block.headings.h3"></a>
        <span class="phrase"><a name="quickbook.syntax.block.headings.heading_4"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_4">Heading
        4</a>
      </h5>
<h6>
<a name="quickbook.syntax.block.headings.h4"></a>
        <span class="phrase"><a name="quickbook.syntax.block.headings.heading_5"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_5">Heading
        5</a>
      </h6>
<h4>
<a name="quickbook.syntax.block.headings.h5"></a>
        <span class="phrase"><a name="quickbook.syntax.block.headings.heading_6"></a></span><a class="link" href="block.html#quickbook.syntax.block.headings.heading_6">Heading
        6</a>
      </h4>
<p>
        You can specify an id for a heading:
      </p>
<pre class="programlisting">[h1:heading_id A heading to link to]
</pre>
<p>
        To link to it, you'll need to include the enclosing section's id:
      </p>
<pre class="programlisting">[link document_id.section_id.heading_id The link text]
</pre>
<p>
        Although you can preceed a heading by an <a class="link" href="phrase.html#quickbook.ref.anchors">anchor</a>
        if you wish to use a location independent link.
      </p>
<p>
        If a heading doesn't have an id, one will be automatically generated with
        a normalized name with <code class="literal">name="document_id.section_id.normalized_header_text"</code>
        (i.e. valid characters are <code class="literal">a-z</code>, <code class="literal">A-Z</code>,
        <code class="literal">0-9</code> and <code class="literal">_</code>. All non-valid characters
        are converted to underscore and all upper-case are converted to lower-case.
        For example: Heading 1 in section Section 2 will be normalized to <code class="literal">section_2.heading_1</code>).
        You can use:
      </p>
<pre class="programlisting">[link document_id.section_id.normalized_header_text The link text]
</pre>
<p>
        to link to them. See <a class="link" href="phrase.html#quickbook.ref.anchor_links">Anchor links</a>
        and <a class="link" href="structure.html#quickbook.ref.section">Section</a> for more info.
      </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
          Specifying heading ids is a quickbook 1.6 feature, earlier versions don't
          support them.
        </p></td></tr>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.generic_heading"></a><a name="quickbook.ref.generic_heading"></a><a class="link" href="block.html#quickbook.syntax.block.generic_heading" title="Generic Heading">Generic
      Heading</a>
</h3></div></div></div>
<p>
        In cases when you don't want to care about the heading level (1 to 6), you
        can use the <span class="emphasis"><em>Generic Heading</em></span>:
      </p>
<pre class="programlisting">[heading Heading]
</pre>
<p>
        The <span class="emphasis"><em>Generic Heading</em></span> assumes the level, plus one, of
        the innermost section where it is placed. For example, if it is placed in
        the outermost section, then, it assumes <span class="emphasis"><em>h2</em></span>.
      </p>
<p>
        Headings are often used as an alternative to sections. It is used particularly
        if you do not want to start a new section. In many cases, however, headings
        in a particular section is just flat. Example:
      </p>
<pre class="programlisting">[section A]
[h2 X]
[h2:link_id Y]
[h2 Z]
[endsect]
</pre>
<p>
        Here we use h2 assuming that section A is the outermost level. If it is placed
        in an inner level, you'll have to use h3, h4, etc. depending on where the
        section is. In general, it is the section level plus one. It is rather tedious,
        however, to scan the section level everytime. If you rewrite the example
        above as shown below, this will be automatic:
      </p>
<pre class="programlisting">[section A]
[heading X]
[heading Y]
[heading Z]
[endsect]
</pre>
<p>
        They work well regardless where you place them. You can rearrange sections
        at will without any extra work to ensure correct heading levels. In fact,
        with <span class="emphasis"><em>section</em></span> and <span class="emphasis"><em>heading</em></span>, you have
        all you need. <span class="emphasis"><em>h1</em></span>..<span class="emphasis"><em>h6</em></span> becomes redundant.
        <span class="emphasis"><em>h1</em></span>..<span class="emphasis"><em>h6</em></span> might be deprecated in the
        future.
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.macros"></a><a name="quickbook.ref.macros"></a><a class="link" href="block.html#quickbook.syntax.block.macros" title="Macros">Macros</a>
</h3></div></div></div>
<pre class="programlisting">[def macro_identifier some text]
</pre>
<p>
        When a macro is defined, the identifier replaces the text anywhere in the
        file, in paragraphs, in markups, etc. macro_identifier is a string of non-
        white space characters except ']'. A macro may not follow an alphabetic character
        or the underscore. The replacement text can be any phrase (even marked up).
        Example:
      </p>
<pre class="programlisting">[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&amp;amp;type=1]]
sf_logo
</pre>
<p>
        Now everywhere the sf_logo is placed, the picture will be inlined.
      </p>
<p>
        <span class="inlinemediaobject"><img src="http://sourceforge.net/sflogo.php?group_id=28447&amp;type=1"></span>
      </p>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
          It's a good idea to use macro identifiers that are distinguishable. For
          instance, in this document, macro identifiers have two leading and trailing
          underscores (e.g. <code class="literal">__spirit__</code>). The reason is to avoid
          unwanted macro replacement.
        </p></td></tr>
</table></div>
<p>
        Links (URLS) and images are good candidates for macros. <span class="bold"><strong>1</strong></span>)
        They tend to change a lot. It is a good idea to place all links and images
        in one place near the top to make it easy to make changes. <span class="bold"><strong>2</strong></span>)
        The syntax is not pretty. It's easier to read and write, e.g. <code class="literal">__spirit__</code>
        than <code class="computeroutput">[@http://spirit.sourceforge.net Spirit]</code>.
      </p>
<p>
        Some more examples:
      </p>
<pre class="programlisting">[def :-)            [$theme/smiley.png]]
[def __spirit__     [@http://spirit.sourceforge.net Spirit]]
</pre>
<p>
        (See <a class="link" href="phrase.html#quickbook.ref.images">Images</a> and <a class="link" href="phrase.html#quickbook.ref.links">Links</a>)
      </p>
<p>
        Invoking these macros:
      </p>
<pre class="programlisting">Hi __spirit__  :-)
</pre>
<p>
        will generate this:
      </p>
<p>
        Hi <a href="http://spirit.sourceforge.net" target="_top">Spirit</a> <span class="inlinemediaobject"><img src="../../../src/images/smiley.png"></span>
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.predefined_macros"></a><a name="quickbook.ref.predefined_macros"></a><a class="link" href="block.html#quickbook.syntax.block.predefined_macros" title="Predefined Macros">Predefined
      Macros</a>
</h3></div></div></div>
<p>
        Quickbook has some predefined macros that you can already use.
      </p>
<div class="table">
<a name="quickbook.syntax.block.predefined_macros.predefined_macros"></a><p class="title"><b>Table 46.3. Predefined Macros</b></p>
<div class="table-contents"><table class="table" summary="Predefined Macros">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Macro
                </p>
              </th>
<th>
                <p>
                  Meaning
                </p>
              </th>
<th>
                <p>
                  Example
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <code class="literal">__DATE__</code>
                </p>
              </td>
<td>
                <p>
                  Today's date
                </p>
              </td>
<td>
                <p>
                  2025-Aug-06
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="literal">__TIME__</code>
                </p>
              </td>
<td>
                <p>
                  The current time
                </p>
              </td>
<td>
                <p>
                  07:01:47 PM
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="literal">__FILENAME__</code>
                </p>
              </td>
<td>
                <p>
                  Quickbook source filename
                </p>
              </td>
<td>
                <p>
                  block.qbk
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.templates"></a><a name="quickbook.ref.templates"></a><a class="link" href="block.html#quickbook.syntax.block.templates" title="Templates">Templates</a>
</h3></div></div></div>
<p>
        Templates provide a more versatile text substitution mechanism. Templates
        come in handy when you need to create parameterizable, multi-line, boilerplate
        text that you specify once and expand many times. Templates accept one or
        more arguments. These arguments act like place-holders for text replacement.
        Unlike simple macros, which are limited to phrase level markup, templates
        can contain block level markup (e.g. paragraphs, code blocks and tables).
      </p>
<p>
        Example template:
      </p>
<pre class="programlisting">[template person[name age what]

Hi, my name is [name]. I am [age] years old. I am a [what].

]
</pre>
<a name="quickbook.ref.template_identifier"></a><h4>
<a name="quickbook.syntax.block.templates.h0"></a>
        <span class="phrase"><a name="quickbook.syntax.block.templates.template_identifier"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.template_identifier">Template Identifier</a>
      </h4>
<p>
        Template identifiers can either consist of:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            An initial alphabetic character or the underscore, followed by zero or
            more alphanumeric characters or the underscore. This is similar to your
            typical C/C++ identifier.
          </li>
<li class="listitem">
            A single character punctuation (a non-alphanumeric printable character)
          </li>
</ul></div>
<h4>
<a name="quickbook.syntax.block.templates.h1"></a>
        <span class="phrase"><a name="quickbook.syntax.block.templates.formal_template_arguments"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.formal_template_arguments">Formal
        Template Arguments</a>
      </h4>
<p>
        Template formal arguments are identifiers consisting of an initial alphabetic
        character or the underscore, followed by zero or more alphanumeric characters
        or the underscore. This is similar to your typical C/C++ identifier.
      </p>
<p>
        A template formal argument temporarily hides a template of the same name
        at the point where the <a class="link" href="phrase.html#quickbook.ref.template_expansion">template
        is expanded</a>. Note that the body of the <code class="literal">person</code> template
        above refers to <code class="literal">name</code> <code class="literal">age</code> and <code class="literal">what</code>
        as <code class="literal">[name]</code> <code class="literal">[age]</code> and <code class="literal">[what]</code>.
        <code class="literal">name</code> <code class="literal">age</code> and <code class="literal">what</code>
        are actually templates that exist in the duration of the template call.
      </p>
<h4>
<a name="quickbook.syntax.block.templates.h2"></a>
        <span class="phrase"><a name="quickbook.syntax.block.templates.template_body"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.template_body">Template
        Body</a>
      </h4>
<p>
        The template body can be just about any QuickBook block or phrase. There
        are actually two forms. Templates may be phrase or block level. Phrase templates
        are of the form:
      </p>
<pre class="programlisting">[template sample[arg1 arg2...argN] replacement text... ]
</pre>
<p>
        Block templates are of the form:
      </p>
<pre class="programlisting">[template sample[arg1 arg2...argN]
replacement text...
]
</pre>
<p>
        The basic rule is as follows: if a newline immediately follows the argument
        list, then it is a block template, otherwise, it is a phrase template. Phrase
        templates are typically expanded as part of phrases. Like macros, block level
        elements are not allowed in phrase templates.
      </p>
<h4>
<a name="quickbook.syntax.block.templates.h3"></a>
        <span class="phrase"><a name="quickbook.syntax.block.templates.template_expansion"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.template_expansion">Template
        Expansion</a>
      </h4>
<p>
        You expand a template this way:
      </p>
<pre class="programlisting">[template_identifier arg1..arg2..arg3]
</pre>
<p>
        At template expansion, you supply the actual arguments. The template will
        be expanded with your supplied arguments. Example:
      </p>
<pre class="programlisting">[person James Bond..39..Spy]
[person Santa Clause..87..Big Red Fatso]
</pre>
<p>
        Which will expand to:
      </p>
<p>
        Hi, my name is James Bond. I am 39 years old. I am a Spy.
      </p>
<p>
        Hi, my name is Santa Clause. I am 87 years old. I am a Big Red Fatso.
      </p>
<div class="caution"><table border="0" summary="Caution">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
<th align="left">Caution</th>
</tr>
<tr><td align="left" valign="top"><p>
          A word of caution: Templates are recursive. A template can call another
          template or even itself, directly or indirectly. There are no control structures
          in QuickBook (yet) so this will always mean infinite recursion. QuickBook
          can detect this situation and report an error if recursion exceeds a certain
          limit.
        </p></td></tr>
</table></div>
<p>
        Each actual argument can be a word, a text fragment or just about any <a class="link" href="phrase.html" title="Phrase Level Elements">QuickBook phrase</a>. Arguments are
        separated by the double dot <code class="literal">".."</code> and terminated
        by the close parenthesis.
      </p>
<p>
        Note that templates and template parameters can't be expanded everywhere,
        only where text is interpreted as a phrase. So they can't be expanded in
        places such as table titles and link's urls. If you want to use a template
        to generate a link based of the template parameter, you can't use a normal
        link and will need to use escaped docbook instead. Example:
      </p>
<pre class="programlisting">[template boost_ticket[key] '''&lt;ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''"&gt;#'''[key]'''&lt;/ulink&gt;''']

[boost_ticket 2035]
</pre>
<p>
        will expand to:
      </p>
<p>
        <a href="https://svn.boost.org/trac/boost/ticket/2035" target="_top">#2035</a>
      </p>
<div class="caution"><table border="0" summary="Caution">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
<th align="left">Caution</th>
</tr>
<tr><td align="left" valign="top"><p>
          Since quickbook doesn't understand the context where the parameter is being
          used, it will interpret it as quickbook markup, so when writing a template
          like this, you'll need to escape any meaningful punctuation.
        </p></td></tr>
</table></div>
<h4>
<a name="quickbook.syntax.block.templates.h4"></a>
        <span class="phrase"><a name="quickbook.syntax.block.templates.nullary_templates"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.nullary_templates">Nullary
        Templates</a>
      </h4>
<p>
        Nullary templates look and act like simple macros. Example:
      </p>
<pre class="programlisting">[template alpha[]&amp;apos;&amp;apos;&amp;apos;&amp;amp;#945;&amp;apos;&amp;apos;&amp;apos;]
[template beta[]&amp;apos;&amp;apos;&amp;apos;&amp;amp;#946;&amp;apos;&amp;apos;&amp;apos;]
</pre>
<p>
        Expanding:
      </p>
<pre class="programlisting">Some squigles...[*[alpha][beta]]</pre>
<p>
        We have:
      </p>
<p>
        Some squiggles...<span class="bold"><strong>αβ</strong></span>
      </p>
<p>
        The difference with macros are
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            The explicit <a class="link" href="phrase.html#quickbook.ref.template_expansion">template
            expansion syntax</a>. This is an advantage because, now, we don't
            have to use obscure naming conventions like double underscores (e.g.
            __alpha__) to avoid unwanted macro replacement.
          </li>
<li class="listitem">
            The template is expanded at the point where it is invoked. A macro is
            expanded immediately at its point of declaration. This is subtle and
            can cause a slight difference in behavior especially if you refer to
            other macros and templates in the body.
          </li>
</ul></div>
<p>
        The empty brackets after the template identifier (<code class="literal">alpha[]</code>)
        indicates no arguments. If the template body does not look like a template
        argument list, we can elide the empty brackets. Example:
      </p>
<pre class="programlisting">[template aristotle_quote Aristotle: [*['Education is the best provision
for the journey to old age.]]]
</pre>
<p>
        Expanding:
      </p>
<pre class="programlisting">Here's a quote from [aristotle_quote].
</pre>
<p>
        We have:
      </p>
<p>
        Here's a quote from Aristotle: <span class="bold"><strong><span class="emphasis"><em>Education
        is the best provision for the journey to old age.</em></span></strong></span>.
      </p>
<p>
        The disadvantage is that you can't avoid the space between the template identifier,
        <code class="computeroutput">aristotle_quote</code>, and the template body "Aristotle...".
        This space will be part of the template body. If that space is unwanted,
        use empty brackets or use the space escape: "<code class="computeroutput">\ </code>".
        Example:
      </p>
<pre class="programlisting">[template tag\ _tag]
</pre>
<p>
        Then expanding:
      </p>
<pre class="programlisting">`struct` x[tag];
</pre>
<p>
        We have:
      </p>
<p>
        <code class="computeroutput">struct</code> x_tag;
      </p>
<p>
        You have a couple of ways to do it. I personally prefer the explicit empty
        brackets, though.
      </p>
<h4>
<a name="quickbook.syntax.block.templates.h5"></a>
        <span class="phrase"><a name="quickbook.syntax.block.templates.simple_arguments"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.simple_arguments">Simple
        Arguments</a>
      </h4>
<p>
        As mentioned, arguments are separated by the double dot <code class="literal">".."</code>.
        Alternatively, if the double dot isn't used and more than one argument is
        expected, QuickBook uses whitespace to separate the arguments, following
        this logic:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            Break the last argument into two, at the first space found (<code class="literal">'',
            '\n', \t' or '\r'</code>).
          </li>
<li class="listitem">
            Repeat until there are enough arguments or if there are no more spaces
            found (in which case, an error is reported).
          </li>
</ul></div>
<p>
        For example:
      </p>
<pre class="programlisting">[template simple[a b c d] [a][b][c][d]]
[simple w x y z]
</pre>
<p>
        will produce:
      </p>
<p>
        wxyz
      </p>
<p>
        "w x y z" is initially treated as a single argument because we
        didn't supply any <code class="literal">".."</code> separators. However,
        since <code class="literal">simple</code> expects 4 arguments, "w x y z"
        is broken down iteratively (applying the logic above) until we have "w",
        "x", "y" and "z".
      </p>
<p>
        QuickBook only tries to get the arguments it needs. For example:
      </p>
<pre class="programlisting">[simple w x y z trail]
</pre>
<p>
        will produce:
      </p>
<p>
        wxyz trail
      </p>
<p>
        The arguments being: "w", "x", "y" and "z
        trail".
      </p>
<div class="caution"><table border="0" summary="Caution">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../doc/src/images/caution.png"></td>
<th align="left">Caution</th>
</tr>
<tr><td align="left" valign="top"><p>
          The behavior described here is for QuickBook 1.5. In older versions you
          could use both the double dot and whitespace as separators in the same
          template call. If your document is marked up as an older version, it will
          use the old behavior, which is described in the <a href="http://www.boost.org/doc/libs/1_40_0/doc/html/quickbook/syntax.html#quickbook.syntax.block.templates.simple_arguments" target="_top">QuickBook
          1.4 documentation</a>.
        </p></td></tr>
</table></div>
<h4>
<a name="quickbook.syntax.block.templates.h6"></a>
        <span class="phrase"><a name="quickbook.syntax.block.templates.punctuation_templates"></a></span><a class="link" href="block.html#quickbook.syntax.block.templates.punctuation_templates">Punctuation
        Templates</a>
      </h4>
<p>
        With templates, one of our objectives is to allow us to rewrite QuickBook
        in QuickBook (as a qbk library). For that to happen, we need to accommodate
        single character punctuation templates which are fairly common in QuickBook.
        You might have noticed that single character punctuations are allowed as
        <a class="link" href="block.html#quickbook.ref.template_identifier">template identifiers</a>.
        Example:
      </p>
<pre class="programlisting">[template ![bar] &lt;hey&gt;[bar]&lt;/hey&gt;]
</pre>
<p>
        Now, expanding this:
      </p>
<pre class="programlisting">[!baz]
</pre>
<p>
        We will have:
      </p>
<pre class="programlisting">&lt;hey&gt;baz&lt;/hey&gt;
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.blurbs"></a><a name="quickbook.ref.blurbs"></a><a class="link" href="block.html#quickbook.syntax.block.blurbs" title="Blurbs">Blurbs</a>
</h3></div></div></div>
<pre class="programlisting">[blurb :-) [*An eye catching advertisement or note...]

    <a href="http://spirit.sourceforge.net" target="_top">Spirit</a> is an object-oriented recursive-descent parser generator framework
    implemented using template meta-programming techniques. Expression templates
    allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
    completely in C++.
]
</pre>
<p>
        will generate this:
      </p>
<div class="blurb">
<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div>
<p>
        <span class="inlinemediaobject"><img src="../../../src/images/smiley.png"></span>
        <span class="bold"><strong>An eye catching advertisement or note...</strong></span>
      </p>
<p>
        <a href="http://spirit.sourceforge.net" target="_top">Spirit</a> is an object-oriented
        recursive-descent parser generator framework implemented using template meta-programming
        techniques. Expression templates allow us to approximate the syntax of Extended
        Backus-Normal Form (EBNF) completely in C++.
      </p>
</div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
          Prefer <a class="link" href="block.html#quickbook.ref.admonitions">admonitions</a> wherever
          appropriate.
        </p></td></tr>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.tables"></a><a name="quickbook.ref.tables"></a><a class="link" href="block.html#quickbook.syntax.block.tables" title="Tables">Tables</a>
</h3></div></div></div>
<pre class="programlisting">[table:id A Simple Table
    [[Heading 1] [Heading 2] [Heading 3]]
    [[R0-C0]     [R0-C1]     [R0-C2]]
    [[R1-C0]     [R1-C1]     [R1-C2]]
    [[R2-C0]     [R2-C1]     [R2-C2]]
]
</pre>
<p>
        will generate:
      </p>
<div class="table">
<a name="quickbook.syntax.block.tables.id"></a><p class="title"><b>Table 46.4. A Simple Table</b></p>
<div class="table-contents"><table class="table" summary="A Simple Table">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Heading 1
                </p>
              </th>
<th>
                <p>
                  Heading 2
                </p>
              </th>
<th>
                <p>
                  Heading 3
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  R0-C0
                </p>
              </td>
<td>
                <p>
                  R0-C1
                </p>
              </td>
<td>
                <p>
                  R0-C2
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  R1-C0
                </p>
              </td>
<td>
                <p>
                  R1-C1
                </p>
              </td>
<td>
                <p>
                  R1-C2
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  R2-C0
                </p>
              </td>
<td>
                <p>
                  R2-C1
                </p>
              </td>
<td>
                <p>
                  R2-C2
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        The table title is optional. The first row of the table is automatically
        treated as the table header; that is, it is wrapped in <code class="literal">&lt;thead&gt;...&lt;/thead&gt;</code>
        XML tags. Note that unlike the original QuickDoc, the columns are nested
        in [cells... ].
      </p>
<p>
        Giving tables an id is a new feature for quickbook 1.5 onwards. As with sections,
        the id is optional. If the table has a title but no id, an id will be generated
        from the title. The table above can be linked to using:
      </p>
<pre class="programlisting">[link quickbook.syntax.block.tables.id link to table]
</pre>
<p>
        which will generate:
      </p>
<p>
        <a class="link" href="block.html#quickbook.syntax.block.tables.id" title="Table 46.4. A Simple Table">link to table</a>
      </p>
<p>
        The syntax is free-format and allows big cells to be formatted nicely. Example:
      </p>
<pre class="programlisting">[table Table with fat cells
    [[Heading 1] [Heading 2]]
    [
        [Row 0, Col 0: a small cell]
        [
            Row 0, Col 1: a big fat cell with paragraphs

            Boost provides free peer-reviewed portable C++ source libraries.

            We emphasize libraries that work well with the C++ Standard Library.
            Boost libraries are intended to be widely useful, and usable across
            a broad spectrum of applications. The Boost license encourages both
            commercial and non-commercial use.
        ]
    ]
    [
        [Row 1, Col 0: a small cell]
        [Row 1, Col 1: a small cell]
    ]
]
</pre>
<p>
        and thus:
      </p>
<div class="table">
<a name="quickbook.syntax.block.tables.table_with_fat_cells"></a><p class="title"><b>Table 46.5. Table with fat cells</b></p>
<div class="table-contents"><table class="table" summary="Table with fat cells">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Heading 1
                </p>
              </th>
<th>
                <p>
                  Heading 2
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  Row 0, Col 0: a small cell
                </p>
              </td>
<td>
                <p>
                  Row 0, Col 1: a big fat cell with paragraphs
                </p>
                <p>
                  Boost provides free peer-reviewed portable C++ source libraries.
                  We emphasize libraries that work well with the C++ Standard Library.
                  Boost libraries are intended to be widely useful, and usable across
                  a broad spectrum of applications. The Boost license encourages
                  both commercial and non-commercial use.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Row 1, Col 0: a small cell
                </p>
              </td>
<td>
                <p>
                  Row 1, Col 1: a small cell
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        Here's how to have preformatted blocks of code in a table cell:
      </p>
<pre class="programlisting">[table Table with code
    [[Comment] [Code]]
    [
        [My first program]
        [``
            #include &lt;iostream&gt;

            int main()
            {
                std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
                return 0;
            }
        ``]
    ]
]
</pre>
<div class="table">
<a name="quickbook.syntax.block.tables.table_with_code"></a><p class="title"><b>Table 46.6. Table with code</b></p>
<div class="table-contents"><table class="table" summary="Table with code">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Comment
                </p>
              </th>
<th>
                <p>
                  Code
                </p>
              </th>
</tr></thead>
<tbody><tr>
<td>
                <p>
                  My first program
                </p>
              </td>
<td>
<pre class="programlisting">#include &lt;iostream&gt;

int main()
{
    std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
    return 0;
}
</pre>
              </td>
</tr></tbody>
</table></div>
</div>
<br class="table-break">
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.variable_lists"></a><a name="quickbook.ref.variable_lists"></a><a class="link" href="block.html#quickbook.syntax.block.variable_lists" title="Variable Lists">Variable
      Lists</a>
</h3></div></div></div>
<pre class="programlisting">[variablelist A Variable List
    [[term 1] [The definition of term 1]]
    [[term 2] [The definition of term 2]]
    [[term 3] [
    The definition of term 3.

    Definitions may contain paragraphs.
    ]]
]
</pre>
<p>
        will generate:
      </p>
<div class="variablelist">
<p class="title"><b>A Variable List</b></p>
<dl class="variablelist">
<dt><span class="term">term 1</span></dt>
<dd><p>
              The definition of term 1
            </p></dd>
<dt><span class="term">term 2</span></dt>
<dd><p>
              The definition of term 2
            </p></dd>
<dt><span class="term">term 3</span></dt>
<dd>
<p>
              The definition of term 3.
            </p>
<p>
              Definitions may contain paragraphs.
            </p>
</dd>
</dl>
</div>
<p>
        The rules for variable lists are the same as for tables, except that only
        2 "columns" are allowed. The first column contains the terms, and
        the second column contains the definitions. Those familiar with HTML will
        recognize this as a "definition list".
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.include"></a><a name="quickbook.ref.include"></a><a class="link" href="block.html#quickbook.syntax.block.include" title="Include">Include</a>
</h3></div></div></div>
<p>
        You can include one QuickBook file from another. The syntax is simply:
      </p>
<pre class="programlisting">[include someother.qbk]
</pre>
<p>
        In quickbook 1.6 and later, if the included file has a <a class="link" href="structure.html#quickbook.ref.docinfo">docinfo
        block</a> then it will create a nested document. This will be processed
        as a standalone document, although any macros or templates from the enclosing
        file will still be defined.
      </p>
<p>
        Otherwise the included file will be processed as if it had been cut and pasted
        into the current document, with the following exceptions:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            The __FILENAME__ predefined macro will reflect the name of the file currently being
            processed.
          </li>
<li class="listitem">
            Any macros or templates defined in the included file are scoped to that
            file, i.e. they are not added to the enclosing file.
          </li>
</ul></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
          In quickbook 1.5 and earlier templates weren't scoped in included files.
          If you want to use templates or macros from a file in quickbook 1.6, use
          <a class="link" href="block.html#quickbook.ref.import">import</a> instead.
        </p></td></tr>
</table></div>
<p>
        The <code class="literal">[include]</code> directive lets you specify a document id
        to use for the included file. You can specify the id like this:
      </p>
<pre class="programlisting">[include:someid someother.qbk]
</pre>
<p>
        All auto-generated anchors will use the document id as a unique prefix. So
        for instance, if there is a top section in someother.qbk named "Intro",
        the named anchor for that section will be "someid.intro", and you
        can link to it with <code class="literal">[link someid.intro The Intro]</code>.
      </p>
<p>
        If the included file has a docinfo block, an id specified in an <code class="literal">[include]</code>
        directive will overwrite it.
      </p>
<p>
        You can also include C, C++ and python source files. This will include any
        quickbook blocks in the file that aren't inside of named code snippets. See
        the <a class="link" href="block.html#quickbook.ref.import">Import section</a> for syntax
        details. For example, say you included this file:
      </p>
<pre class="programlisting">/**
 * Hello world example
 */

// In this comment, the backtick indicates that this is a
// quickbook source block that will be included.

/*`
First include the appropriate header: [hello_includes]
Then write your main function: [hello_main]
*/

// This defines a code snippet, the syntax is
// described in the import section. It's available
// in the whole of this source file, not just after
// its definition.

//[hello_includes
#include &lt;iostream&gt;
//]

//[hello_main
int main() {
    std::cout &lt;&lt; "Hello, trivial example" &lt;&lt; std::endl;
}
//]
</pre>
<p>
        It will generate:
      </p>
<pre class="programlisting">First include the appropriate header:

    #include &lt;iostream&gt;

Then write your main function:

    int main() {
        std::cout &lt;&lt; "Hello, trivial example" &lt;&lt; std::endl;
    }
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.import"></a><a name="quickbook.ref.import"></a><a class="link" href="block.html#quickbook.syntax.block.import" title="Import">Import</a>
</h3></div></div></div>
<p>
        In quickbook 1.6 and later if you wish to use a template, macro or code snippet
        from a file, you need to import it. This will not include any of the content
        from that file, but will pull templates, macros and code snippets into the
        current file's scope.
      </p>
<p>
        With quickbook files, this allows you to create template and macro libraries.
        For python (indicated by the <code class="computeroutput">.py</code> extension), C or C++ files
        this allows you to include code snippets from source files, so that your
        code examples can be kept up to date and fully tested.
      </p>
<h4>
<a name="quickbook.syntax.block.import.h0"></a>
        <span class="phrase"><a name="quickbook.syntax.block.import.example"></a></span><a class="link" href="block.html#quickbook.syntax.block.import.example">Example</a>
      </h4>
<p>
        You can effortlessly import code snippets from source code into your QuickBook.
        The following illustrates how this is done:
      </p>
<pre class="programlisting">[import ../test/stub.cpp]
[foo]
[bar]
</pre>
<p>
        The first line:
      </p>
<pre class="programlisting">[import ../test/stub.cpp]
</pre>
<p>
        collects specially marked-up code snippets from <a href="../../../../tools/quickbook/test/stub.cpp" target="_top">stub.cpp</a>
        and places them in your QuickBook file as virtual templates. Each of the
        specially marked-up code snippets has a name (e.g. <code class="computeroutput">foo</code> and
        <code class="computeroutput">bar</code> in the example above). This shall be the template identifier
        for that particular code snippet. The second and third line above does the
        actual template expansion:
      </p>
<pre class="programlisting">[foo]
[bar]
</pre>
<p>
        And the result is:
      </p>
<p>
        This is the <span class="bold"><strong><span class="emphasis"><em>foo</em></span></strong></span> function.
      </p>
<p>
        This description can have paragraphs...
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            lists
          </li>
<li class="listitem">
            etc.
          </li>
</ul></div>
<p>
        And any quickbook block markup.
      </p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo</span><span class="special">()</span>
<span class="special">{</span>
    <span class="comment">// return 'em, foo man!</span>
    <span class="keyword">return</span> <span class="string">"foo"</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
        This is the <span class="bold"><strong><span class="emphasis"><em>bar</em></span></strong></span> function
      </p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">bar</span><span class="special">()</span>
<span class="special">{</span>
    <span class="comment">// return 'em, bar man!</span>
    <span class="keyword">return</span> <span class="string">"bar"</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
        Some trailing text here
      </p>
<h4>
<a name="quickbook.syntax.block.import.h1"></a>
        <span class="phrase"><a name="quickbook.syntax.block.import.code_snippet_markup"></a></span><a class="link" href="block.html#quickbook.syntax.block.import.code_snippet_markup">Code
        Snippet Markup</a>
      </h4>
<p>
        Note how the code snippets in <a href="../../../../tools/quickbook/test/stub.cpp" target="_top">stub.cpp</a>
        get marked up. We use distinguishable comments following the form:
      </p>
<pre class="programlisting">//[id
some code here
//]
</pre>
<p>
        The first comment line above initiates a named code-snippet. This prefix
        will not be visible in quickbook. The entire code-snippet in between <code class="computeroutput">//[id</code>
        and <code class="computeroutput">//]</code> will be inserted as a template in quickbook with name
        <span class="emphasis"><em><span class="emphasis"><em>id</em></span></em></span>. The comment <code class="computeroutput">//]</code>
        ends a code-snippet This too will not be visible in quickbook.
      </p>
<a name="quickbook.ref.callouts"></a><h4>
<a name="quickbook.syntax.block.import.h2"></a>
        <span class="phrase"><a name="quickbook.syntax.block.import.special_comments"></a></span><a class="link" href="block.html#quickbook.syntax.block.import.special_comments">Special
        Comments</a>
      </h4>
<p>
        Special comments of the form:
      </p>
<pre class="programlisting">//` some [*quickbook] markup here
</pre>
<p>
        and:
      </p>
<pre class="programlisting">/*` some [*quickbook] markup here */
</pre>
<p>
        will be parsed by QuickBook. This can contain quickbook <span class="emphasis"><em>blocks</em></span>
        (e.g. sections, paragraphs, tables, etc). In the first case, the initial
        slash-slash, tick and white-space shall be ignored. In the second, the initial
        slash-star-tick and the final star-slash shall be ignored.
      </p>
<p>
        Special comments of the form:
      </p>
<pre class="programlisting">/*&lt;- this C++ comment will be ignored -&gt;*/
</pre>
<p>
        or
      </p>
<pre class="programlisting">/*&lt;-*/ "this c++ code  will be ignored" /*-&gt;*/
</pre>
<p>
        or
      </p>
<pre class="programlisting">//&lt;-
private:
    int some_member;
//-&gt;
</pre>
<p>
        can be used to inhibit code from passing through to quickbook. All text between
        the delimeters will simply be ignored.
      </p>
<p>
        Comments of this form:
      </p>
<pre class="programlisting">//=int main() {}
</pre>
<p>
        or
      </p>
<pre class="programlisting">/*=foo()*/
</pre>
<p>
        will be displayed as code that isn't in comments. This allows you to include
        some code in the snippet but not actually use it when compiling your example.
      </p>
<h4>
<a name="quickbook.syntax.block.import.h3"></a>
        <span class="phrase"><a name="quickbook.syntax.block.import.callouts"></a></span><a class="link" href="block.html#quickbook.syntax.block.import.callouts">Callouts</a>
      </h4>
<p>
        Special comments of the form:
      </p>
<pre class="programlisting">/*&lt; some [*quickbook] markup here &gt;*/
</pre>
<p>
        will be regarded as callouts. These will be collected, numbered and rendered
        as a "callout bug" (a small icon with a number). After the whole
        snippet is parsed, the callout list is generated. See <a href="http://www.docbook.org/tdg/en/html/callout.html" target="_top">Callouts</a>
        for details. Example:
      </p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">foo_bar</span><span class="special">()</span> <a class="co" name="quickbook.syntax.block.import.c0" href="block.html#quickbook.syntax.block.import.c1"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
<span class="special">{</span>
    <span class="keyword">return</span> <span class="string">"foo-bar"</span><span class="special">;</span> <a class="co" name="quickbook.syntax.block.import.c2" href="block.html#quickbook.syntax.block.import.c3"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a>
<span class="special">}</span>
</pre>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c1"></a><a href="#quickbook.syntax.block.import.c0"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
            The <span class="emphasis"><em>Mythical</em></span> FooBar. See <a href="http://en.wikipedia.org/wiki/Foobar" target="_top">Foobar
            for details</a>
          </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c3"></a><a href="#quickbook.syntax.block.import.c2"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
<td valign="top" align="left"><p>
            return 'em, foo-bar man!
          </p></td>
</tr>
</table></div>
<p>
        This is the actual code:
      </p>
<pre class="programlisting">//[ foo_bar
std::string foo_bar() /*&lt; The /Mythical/ FooBar.
                      See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] &gt;*/
{
    return "foo-bar"; /*&lt; return 'em, foo-bar man! &gt;*/
}
//]
</pre>
<p>
        The callouts bugs are placed exactly where the special callout comment is
        situated. It can be anywhere in the code. The bugs can be rather obtrusive,
        however. They get in the way of the clarity of the code. Another special
        callout comment style is available:
      </p>
<pre class="programlisting">/*&lt;&lt; some [*quickbook] markup here &gt;&gt;*/
</pre>
<p>
        This is the line-oriented version of the callout. With this, the "bug"
        is placed at the very left of the code block, away from the actual code.
        By placing it at the far left, the code is rendered un-obscured. Example:
      </p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">x</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>

    <a class="co" name="quickbook.syntax.block.import.c4" href="block.html#quickbook.syntax.block.import.c5"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a><span class="identifier">x</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">n</span><span class="special">(</span><span class="number">0</span><span class="special">)</span>
    <span class="special">{</span>
    <span class="special">}</span>

    <a class="co" name="quickbook.syntax.block.import.c6" href="block.html#quickbook.syntax.block.import.c7"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a><span class="special">~</span><span class="identifier">x</span><span class="special">()</span>
    <span class="special">{</span>
    <span class="special">}</span>

    <a class="co" name="quickbook.syntax.block.import.c8" href="block.html#quickbook.syntax.block.import.c9"><img src="../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a><span class="keyword">int</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span>
    <span class="special">{</span>
        <span class="keyword">return</span> <span class="identifier">n</span><span class="special">;</span>
    <span class="special">}</span>

    <a class="co" name="quickbook.syntax.block.import.c10" href="block.html#quickbook.syntax.block.import.c11"><img src="../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a><span class="keyword">void</span> <span class="identifier">set</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n_</span><span class="special">)</span>
    <span class="special">{</span>
        <span class="identifier">n</span> <span class="special">=</span> <span class="identifier">n_</span><span class="special">;</span>
    <span class="special">}</span>
<span class="special">};</span>
</pre>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c5"></a><a href="#quickbook.syntax.block.import.c4"><img src="../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
            Constructor
          </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c7"></a><a href="#quickbook.syntax.block.import.c6"><img src="../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
<td valign="top" align="left"><p>
            Destructor
          </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c9"></a><a href="#quickbook.syntax.block.import.c8"><img src="../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td>
<td valign="top" align="left"><p>
            Get the <code class="computeroutput">n</code> member variable
          </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="quickbook.syntax.block.import.c11"></a><a href="#quickbook.syntax.block.import.c10"><img src="../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a> </p></td>
<td valign="top" align="left"><p>
            Set the <code class="computeroutput">n</code> member variable
          </p></td>
</tr>
</table></div>
<p>
        See the actual code here: <a href="../../../../tools/quickbook/test/stub.cpp" target="_top">tools/quickbook/test/stub.cpp</a>
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.syntax.block.block"></a><a name="quickbook.ref.block"></a><a class="link" href="block.html#quickbook.syntax.block.block" title="Plain blocks">Plain
      blocks</a>
</h3></div></div></div>
<p>
        <code class="computeroutput">block</code> is a plain block element, that doesn't wrap its contents
        in any docbook or boostbook tags. This can be useful when using escaped docbook
        block tags, such as:
      </p>
<pre class="programlisting">[template chapter[title]
[block'''&lt;chapter&gt;&lt;title&gt;'''[title]'''&lt;/title&gt;''']
]

[template chapterend
[block'''&lt;/chapter&gt;''']
]

[chapter An example chapter]

Content

[chapterend]
</pre>
<p>
        Without the <code class="computeroutput">block</code> element, the <code class="computeroutput">chapter</code> and <code class="computeroutput">chapterend</code>
        templates would be wrapped in paragraph tags.
      </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
          In this example, the template body has to start with a newline so that
          the template will be interpreted in block mode.
        </p></td></tr>
</table></div>
</div>
</div>
<div class="copyright-footer">Copyright © 2002, 2004, 2006 Joel de Guzman,
      Eric Niebler<br>Copyright © 2010-2017 Daniel James<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="phrase.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../quickbook.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../versions.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
